You can download the workshop material on github.
Don’t hesitate to comment (new issues), or request changes (pull request) on .
Follow the .html (web browser) and the .Rmd (Rstudio) documents. Try and experiment.
~2 hours: Introduction and practice
~15 minutes: pause
~1 hour: other formats (.docx, .pdf). Workshop here
~15 minutes: shiny. Workshop here
Markdown is a lightweight markup language with plain text formatting syntax (Easy-to-read, easy-to-write plain text format). It is designed so that it can be easily converted to HTML and many other formats (e.g. PDF, MS Word, .docx).
Like other markup languages (e.g. HTML and Latex), it is completely independent from R.
Typically, file have the extension .md.
Look at this example. Examine the html render (github automatically interprets .md files) and raw file.
An extension of the markdown syntax that enables R code to be embedded and executed.
Generate fully reproducible reports in different of static and dynamic output formats.
Most of these packages are maintained by the Rstudio team (https://rmarkdown.rstudio.com/, Yihui Xie)
Plain text files that typically have the file extension .Rmd.
Write text & code in Rstudio.
Knit: The R package rmarkdown feeds the .Rmd file to the R package knitr.
knitr executes code and creates a new markdown (.md) document which includes the code and output.
Subsequently tranformed into .html/.tex/.docx by pandoc. (Note that .tex files need to be transformed by pdflatex into .pdf files. We’ll come back to that later.)
Pandoc is an universal document converter, independent of R.
By default, Rstudio comes with rmarkdown, knitr, and pandoc (but not pdflatex).
When you click the Knit button (top left), a document will be generated that includes both content as well as the output of R code within the document.
R studio
file > new file > R markdown > HTML
Save it (“myfirstRmarkdown.Rmd”)
Knit
Examine the .html output.
Examine at the .Rmd file structure.
Markdown provides an easy way to make standard types of formatted text, like:
italics (*text*) or italics (_text_)
bold (**bold**)
backslash (\) to interpret a special characters as character
# and space at the beginning of line for a header level (6 levels, # to ######)
bold italic (_**bold italic**_)
links ([links](https://www.rmarkdown.rstudio.com))
Two spaces for a newline character
“ ” character (html Non-Breaking SPace) for extra line spacing can be useful.
quoted text (`quoted text`)
> Quoted text: 1st way
> more quoted text
> still more quoted text
Quoted text: 1st way
more quoted text
still more quoted text
`Quoted text: 2nd way`
`more quoted text`
`still more quoted text`
Quoted text: 2nd way
more quoted text
still more quoted text
```
text: 3rd way
quoted text
more quoted text
```
Quoted text: 3rd way
more quoted text
still more quoted text
Species | Counts
——— | —–
H. sapiens | 24
M. musculus | 442
| Species | Counts |
|---|---|
| H. sapiens | 24 |
| M. musculus | 442 |
---
title: "Rmarkdown"
author: "Sebastien Renaut"
date: '2018-03-12'
output: html_document
---
Header, metadata, YAML, YAML Ain’t Markup Language (https://en.wikipedia.org/wiki/YAML#History_and_name) ?
Header specifies configurations (what kind of document will be created, and the options chosen).
It is not required (defaults then apply).
It uses Python-style indentation to specify certain options.
Many options possible depending what type of document you are generating. See below for some examples.
Note that some options can be specified either for the whole document (in the header), the code chunks, or both (chunks options supersede header). More on code chunks later.
---
title: "Rmarkdown"
author: "Sebastien Renaut"
date: "February 27, 2019"
output:
#pdf_document:
html_document:
highlight: tango
number_sections: T
theme: united
toc: yes
toc_depth: 3
---
R functionSee the documentation for more information. But these are some formats of interest:
output: html_document
output: ioslides_presentation
output: pdf_document (This will require that you have a Latex software installed - We’ll get to that later).
output: word_document (.docx)
interactive shiny apps (We’ll get to that later).
toc: yes Generate TOC.
toc_depth:3 depth of TOC.
number_sections:T Add section numbering to headers. If you do not want a certain heading to be numbered, you can add {-} or {.unnumbered} after the heading, e.g.,
theme: specifies the theme to use for the page (“cerulean”, “journal”, “flatly”, “readable”, “spacelab”, “united”, and “cosmo”).
highlight: Syntax highlighting style (e.g. “tango”, “pygments”, “kate”, “zenburn”).
See this Reference guide for more options.
Rmarkdown documentoutput: word_documentThe real power of R Markdown comes from mixing markdown with chunks of code.
A code chunk is intepreted by knitr. It works essentially the same as the R syntax we are familiar with.
A main code chunks may look like this:
```{r code chunk example, include = T, message = T, warning=T, echo = T, fig.cap="Figure 1"}
#Running some R code.
x = rexp(1000)
min(x)
max(x)
plot(x)
```
On the 1st line, I specify that I will run the R programming language.
Then, I give the chunk a UNIQUE name and specify options.
include = F: Code and results will NOT appear in the finished file. Code is still interpreted, and the results can be used by other chunks.
echo = FALSE prevents code, but not results from appearing in the finished file. This is a useful way to embed figures.
message = FALSE prevents messages that are generated by code from appearing in the finished file.
warning = FALSE prevents warnings that are generated by code from appearing in the finished file.
fig.cap = "..." adds a caption to graphical results.
fig.width=..., fig.height=... can also change figure width/heigth.
By default R studio creates a Global Options code chunk. Let’s examine this chunk:
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
see cheat sheet for more info.
Note that you also run inline code using the using the ` ` symbols and specifying the programming language. For example, ` r 10+5 ` would be processes as 15.
R markdown can read and execute different languages!
## rmarkdown_main.Rmd
## rmarkdown_main.html
## rmarkdown_main.log
## rmarkdown_main.tex
## rmarkdown_word_pdf.Rmd
## rmarkdown_word_pdf.html
## rmarkdown_word_pdf.pdf
## rmarkdown_word_pdf.tex
## rsconnect
## shiny.Rmd
## test.Rmd
## test.html
## ['hello', 'python!']
## Hello perl!
Mathematical material is set off by the use of single dollar-sign characters (similar as in the LaTeX typesetting language).
So to write \(E = mc^{2}\), you’d write: $E = mc^{2}$
\(\sum_{i=1}^n ASV\)
\(F_{(1,69)}\) = 1.27, p-value=0.26
\(A = \pi*r^{2}\)
\(\sqrt{b^2 - 4ac}\)
If you wish to use a dollar sign, you need to preface it with a back-slash \(E = mc^{2}\) versus $E = mc^{2}$
The use of double dollars quote allows for displayed formulas (centered). \[\sqrt{b^2 - 4ac}\]
See more example equations from this McGill math Rmarkdown tutorial.
There are several ways to include figures.
Can be included from an URL directly uploaded from the web:
{width=250px}
If this figure is small, it can be added to the text directly: eg.: Today, we are using to generate webpages with
images…
This is a graph previously saved in the figures directory
{width=250px}
pandoc and not knitr, so pandoc options need to be specified, not R graphics options:
It’s simple, but options are tricky.
You may need to play with spacing, figure size, and figure position.
Options are specified directly after the URL or link (eg. {width=250px} or {width=50%}).
Images can also be interpreted by knitr as below:
```{r graphic_example, out.width = "20%", fig.cap = "An orange man", echo = F,fig.align = "center"}
knitr::include_graphics("../figures/orange.jpeg")
```
An orange man
R code, specified in a code chunk (R options specified in the code chunk) and interpreted by knitr as we did previously.```{r another example, echo = T, message = F}
library(ggplot2)
mtcars_ggplot = ggplot(mtcars, aes(x=wt, y=mpg)) +
geom_point() + geom_smooth()
mtcars_ggplot
```
library(ggplot2)
mtcars_ggplot = ggplot(mtcars, aes(x=wt, y=mpg)) +
geom_point() + geom_smooth()
mtcars_ggplotBy default, R Markdown displays data frames and matrices as they would be in the R terminal (in a monospaced font).
You can use the knitr::kable function for additional formatting, as in the .Rmd file below.
## mpg cyl disp hp drat wt qsec vs am gear carb
## Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
## Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
## Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
## Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1
## Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2
## Valiant 18.1 6 225 105 2.76 3.460 20.22 1 0 3 1
#With kable function from knitr (better looking)
knitr::kable(head(mtcars),digits =1,caption = "A motorcars table")| mpg | cyl | disp | hp | drat | wt | qsec | vs | am | gear | carb | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Mazda RX4 | 21.0 | 6 | 160 | 110 | 3.9 | 2.6 | 16.5 | 0 | 1 | 4 | 4 |
| Mazda RX4 Wag | 21.0 | 6 | 160 | 110 | 3.9 | 2.9 | 17.0 | 0 | 1 | 4 | 4 |
| Datsun 710 | 22.8 | 4 | 108 | 93 | 3.8 | 2.3 | 18.6 | 1 | 1 | 4 | 1 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 | 3.1 | 3.2 | 19.4 | 1 | 0 | 3 | 1 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 | 3.1 | 3.4 | 17.0 | 0 | 0 | 3 | 2 |
| Valiant | 18.1 | 6 | 225 | 105 | 2.8 | 3.5 | 20.2 | 1 | 0 | 3 | 1 |
Find a picture on the web.
Add it to document using either knitr or pandoc.
Add a table using knitr.
Footnotes are easy when you have a few references. Use [^1] and add reference at the end using same format.1
Otherwise, you may specify a bibliography and citation style in the header.
---
csl: csl/peerj.csl
bibliography: biblio/test_library.bib
---
The Citation Style Language (.csl) file specifies the reference format.
It is an open XML-based language to describe the formatting of citations and bibliographies. Reference management programs using .csl include Zotero, Mendeley and Papers.
Most journals should have a .csl file be on this github repo. But you could create your own.
A .bib file contains the bibliographic information of your document.
Here, I created a a .bib file in the reference management software Papers3.
But now, I often copy .bib reference directly from google scholar.
Example: The bioinformatics program BLAST (Altschul et al., 1997) has been cited nearly 70,000 times!
These are three random references (eg. Thibert-Plante & Hendry, 2010; Wagner et al., 2012; Yoshida et al., 2014).
Citations go inside square brackets [ ] and are separated by semicolons (;).
Each citation must have a unique key, composed of ‘@’ + the citation identifier from the .bib database.
A minus sign (-) before the @ will suppress mention of the author in the citation. This can be useful when the author is already mentioned in the text. For example, Stephen Altschul and a bunch of other people (1997) have been cited 70,000 times.
Create a library (.bib file) with the references for your five favorite scientific papers.
Find and use another Citation Style Language (e.g. Nature, PLOS ONE, Indian Journal Of Dermatology, etc.).
(Note that references below are generated automatically, except for the footnote.)
Altschul SF., Madden TL., Schäffer AA., Zhang J., Zhang Z., Miller W., Lipman DJ. 1997. Gapped blast and psi-blast: A new generation of protein database search programs. Nucleic acids research 25:3389–3402.
Thibert-Plante X., Hendry A. 2010. The consequences of phenotypic plasticity for ecological speciation. Journal Of Evolutionary Biology:1–17.
Wagner CE., Keller I., Wittwer S., Selz OM., Mwaiko S., Greuter L., Sivasundar A., Seehausen O. 2012. Genome-wide RAD sequence data provide unprecedented resolution of species boundaries and relationships in the Lake Victoria cichlid adaptive radiation. 22:787–798.
Yoshida K., Makino T., Yamaguchi K., Shigenobu S., Hasebe M., Kawata M., Kume M., Mori S., Peichel CL., Toyoda A., Fujiyama A., Kitano J. 2014. Sex Chromosome Turnover Contributes to Genomic Divergence between Incipient Stickleback Species. PLoS Genetics 10:e1004223.
Renaut 2019. R markdown footnote. Number 1. pp1-2↩